Developer CD Series 1999 July: Mac OS SDK/Dev.CD Jul 99 SDK1.toast/Development Kits/Mac OS/NSL 1.0 SDK/Headers & Source/NSLAPI.h

C/C++ Source or Header | 1998-10-05 | 16.8 KB | 422 lines | [TEXT/CWIE]

/*
    File:        NSLAPI.h

    Contains:    API for using the NSL Manager

    Written by:    Kevin Arnold & Dave Fisher

    Copyright:    © 1997 - 1998 by Apple Computer, Inc., all rights reserved.

    Change History (most recent first):

    <43>    6/9/98         DMF        Moved non-public code and dec'ls to NSLTypedDataUtilities.c,h
    <42>    5/3/98        DMF        Removed kNSLMismatchedBufferLengths enum element
    <41>    5/3/98        DMF        Added kNSLNewDataEvent and kNSLContinueLookupEvent events
    <40>    4/16/98        DMF        Updated the values of the error returns.  (in the comments)
    <39>    4/10/98        KA        Added kNBPProtocolType
    <38>    4/09/98        DMF        removed kNSLItemAlreadyInList enum
    <37>    4/02/98        KA        readjusted the comments for the error nums
    <36>    3/30/98        DMF        Added kNSLNullNeighborhoodPtr enum
                                Added kNSLSomePluginsFailedToLoad enum
    <34>    3/26/98        KA        Removed outdated errors as well as protocol specific errors
    <33>    3/25/98        DMF        Added kNSLBadDomainName enum value
    <32>    3/23/98        DMF        Added kNSLNoPluginsForSearch enum value
    <31>    3/18/98        KA        Changed kLastAndMeaningLessItemInEnum to kLastAndMeaningLessItemInNSLEnum
    <30>    3/12/98        KA        Modified NSLParseRegistrationPB
    <29>    3/9/98        DMF        Removed ClientAsyncInfo.totalItems and ClientAsyncInfo.alertThreshold
                                Changed PluginAsyncInfo.searchEvent to PluginAsyncInfo.searchDataType
    <28>    3/9/98        KA        changed method to NSLMakeNewNeighborhood and added NSLFreeNeighborhood
    <27>    3/6/98        KA        oops, forgot to get rid of the index...
    <26>    3/6/98        KA        changed GetNth... to GetNext... iterators
    <25>    3/6/98        KA        Took out references to protocolListOffset
    <24>    3/6/98        KA&DMF    Made more cleanup and standardization of calls
    <23>    3/6/98        KA        Created functions: GetNthNSLNeighborhood and GetNthNSLUrl
    <22>    3/5/98        KA&DMF    Added concept of "NSLNeighborhood" which can denote a domain, zone, realm etc.
    <22>    3/5/98        KA&DMF    Changed "Create" to "Make" in various calls
    <21>    3/3/98        KA        Added kNSLPluginLoadFailed and kNSLNoPluginsFound errors
    <20>    2/20/98        DMF        Added startTime and intStartTime to ClientAsyncInfo struct
    <19>    2/20/98        DMF        Added kNSLMainThreadNotPausable error
    <18>    2/12/98        DMF        Added asyncInfoPtr to NSLCreateRequest call
                                Removed kNSLSearchStateNotifyClient
    <17>    2/11/98        DMF        Switched error returns to NSLError
    <16>    2/5/98        DMF        Split AsyncInfo into PluginAsyncInfo and ClientAsyncInfo
    <16>    2/5/98        DMF        Removed NSLGetNumResponders and NSLAddResultBuffer
    <16>    2/5/98        DMF        Changed most API calls to return NSLError instead of OSStatus
    <15>    2/4/98        DMF        Added asynchronous notification capability
    <14>    2/3/98        DMF        Changed NSLErrNumToString to handle primary and secondary strings
    <14>    2/3/98        DMF        Cleaned up commented out code etc.
    <13>    2/2/98        DMF        Added NSLContinueLookup, mods to AsyncInfo
    <0>        9/24/97        DMF        created (basing APIs on InternetServiceLocationAPI.h)


    To Do:
*/



#ifndef __NSLAPI__
#define __NSLAPI__

#pragma export on


#define kMinNSLSystemVersion        (0x0800)                    // equiv. to 8.0
#define    kMinNSLOTVersion            (0x0130)                    // equiv. to 1.3
#define    kDefaultListSize            256                            // default list size for service and protocol lists
#define    kURLDelimiter                ','                            // delimits URL's within memory buffers
#define    kNSLNoContext                0                            // the default context for NSLError structs
#define    kNSLErrorNoErr                {noErr, kNSLNoContext}

#if __cplusplus
extern "C" {
#endif

typedef struct NSLError
{
    OSStatus    theErr;
    UInt32        theContext;
} NSLError, *NSLErrorPtr;


enum
{
    // Constants to use with NSLPrepareRequest

// this next one is not strictly an error.  The client is free to ignore this return, and nothing bad will happen
// if it does.  It is informational only.
    kDuplicateSearchInProgress                = 100,

    // Invalid enumeratorRef
    kNSLInvalidEnumeratorRef                = 0,        // this is not an error; it is the equiv to a NULL ptr

    // State codes for notifiers.
    kNSLSearchStateBufferFull                = 1,
    kNSLSearchStateOnGoing,
    kNSLSearchStateComplete,
    kNSLSearchStateStalled,
    kNSLWaitingForContinue,

    // Event codes
    kNSLServicesLookupDataEvent,
    kNSLNeighborhoodLookupDataEvent,
    kNSLNewDataEvent,
    kNSLContinueLookupEvent,

    // Error codes
    kNSLNavigationAPIErrorBase                    = -4200,

// UNABLE TO INITIALIZE THE MANAGER!!!!!  DO NOT CONTINUE!!!!
    kNSLInitializationFailed                = kNSLNavigationAPIErrorBase,

// General NSL error codes.  If you change any of this part of the enum, please update the code values
// given in the comments.  1/21/98 DMF

    kNSLNotInitialized,                                        // -4199
    kNSLInsufficientSysVer,                                    // -4198
    kNSLInsufficientOTVer,                                    // -4197
    kNSLNoElementsInList,                                    // -4196
    kNSLBadReferenceErr,                                    // -4195
    kNSLBadServiceTypeErr,                                    // -4194
    kNSLBadDataTypeErr,                                        // -4193
    kNSLBadNetConnection,                                    // -4192
    kNSLNoSupportForService,                                // -4191
    kNSLInvalidPluginSpec,                                    // -4190
//    kNSLMismatchedBufferLengths,                            // -4189
    kNSLRequestBufferAlreadyInList,                            // -4189
    kNSLNoContextAvailable,                                    // -4188    (ContinueLookup function ptr invalid)
    kNSLBufferTooSmallForData,                                // -4187    (Client buffer too small for data from plugin)
    kNSLCannotContinueLookup,                                // -4186    (Can't continue lookup; error or bad state)
    kNSLBadClientInfoPtr,                                    // -4185    (nil ClientAsyncInfoPtr; no reference available)
    kNSLNullListPtr,                                        // -4184    (client is trying to add items to a nil list)
    kNSLBadProtocolTypeErr,                                    // -4183    (client is trying to add a null protocol type)
    kNSLPluginLoadFailed,                                    // -4182    (manager unable to load one of the plugins)
    kNSLNoPluginsFound,                                        // -4181    (manager didn't find any valid plugins to load)
    kNSLSearchAlreadyInProgress,                            // -4180    (you can only have one ongoing search per clientRef)
    kNSLNoPluginsForSearch,                                    // -4179    (no plugins will respond to search request; bad protocol(s)?)
    kNSLNullNeighborhoodPtr,                                // -4178    (client passed a null neighborhood ptr)
    kNSLSomePluginsFailedToLoad,                            // -4177    (one or more plugins failed to load, but at
                                                            //            least one did load; this error isn't fatal)

    NSLErrNullPtrError,                                        // -4176
    kNSLNotImplementedYet,                                    // -4175

    kLastAndMeaningLessItemInNSLEnum
};

typedef    UInt32                NSLEventCode;
typedef    UInt32                NSLRequestRef;
typedef    UInt32                NSLDomainEnumeratorRef;
typedef    UInt32                OneBasedIndex;

typedef UInt16                NSLPort;
typedef char*                NSLPath;
typedef char*                NSLServiceComments;
typedef char*                NSLServiceType;
typedef Handle                NSLServicesList;
typedef char*                NSLAttribute;
typedef unsigned char*        NSLNeighborhood;            // this is a pstring describing the textual Neighborhood name followed by a
                                                        // cstring which is a comma delimited list of protocols which can be used to
                                                        // create a NSLProtocolList internally

typedef UInt32                NSLPluginSpec;
typedef UInt32                NSLClientRef;
typedef UInt16                NSLSearchState;                // longer lasting states of the search
typedef UInt16                NSLDataType;

// the async information block for client<->manager interaction
typedef struct ClientAsyncInfo
{
    void*            clientContextPtr;                    // set by the client for its own use
    void*            mgrContextPtr;                        // set by NSL mgr; ptr to request object ptr
    char*            resultBuffer;
    long            bufferLen;
    long            maxBufferSize;
    UInt32            startTime;                            // when the search starts, to use with maxSearchTime to determine time-out condition
    UInt32            intStartTime;                        // used with alertInterval
    UInt32            maxSearchTime;                        // total time for search, in ticks (0 == no time limit)
    UInt32            alertInterval;                        // call client's notifier or return, every this many ticks ( 0 == don't use this param)
    UInt32            totalItems;                            // total number of tuples currently in buffer
    UInt32            alertThreshold;                        // call client's notifier or return, every this many items found ( 0 == don't use this param)
    NSLSearchState    searchState;
    NSLError        searchResult;
    UInt32            searchDataType;                        // this is a data type code which allows the client's asyncNotifier to properly
} ClientAsyncInfo, *ClientAsyncInfoPtr;                    // handle the data in resultBuffer.


// the async information block plugin<->manager interaction
typedef struct PluginAsyncInfo
{
    void*            mgrContextPtr;                        // set by NSL mgr; ptr to request object ptr
    void*            pluginContextPtr;                    // set/used by individual plugins
    void*            pluginPtr;                            // ptr to the plugin object waiting for continue lookup call
    char*            resultBuffer;                        // set by plugin to point at data
    long            bufferLen;
    long            maxBufferSize;
    UInt32            maxSearchTime;                        // total time for search, in ticks (0 == no time limit)
    UInt32            reserved1;
    UInt32            reserved2;
    UInt32            reserved3;
    NSLClientRef    clientRef;
    NSLRequestRef    requestRef;
    NSLSearchState    searchState;
    OSStatus        searchResult;
} PluginAsyncInfo, *PluginAsyncInfoPtr;


// the mgr asynchronous notifier routine.
typedef pascal void        (*NSLMgrNotifyProcPtr)(void* thePluginAsyncInfo);

// the client asynchronous notifier routine.
typedef pascal void        (*NSLClientNotifyProcPtr)(void* theClientAsyncInfo);

// the NSLContinueLookup routine that is stored in mgrContextPtr
typedef pascal NSLError        (*NSLContinueLookupPtr)(PluginAsyncInfoPtr theAsyncInfo);


// this struct is a format for dealing with our internal data representation.  Typed data will be contiguous chunk of
// memory, with the first 4 bytes being a data "descriptor".
typedef struct TypedData {
    unsigned long            dataType;
    unsigned long            lengthOfData;
//    void*                        theData;
} TypedData, *TypedDataPtr;

#define kNSLDataType        'NSL_'

// This is just a header at the beginning of a handle that stores our list of service types.
// Each service type is a pascal string, so each service type starts after the end of the
// previous one.
typedef struct NSLServicesListHeader {
    unsigned long    numServices;
    unsigned long    logicalLen;                        // length of all usable data in handle
//    Ptr                firstService;
} NSLServicesListHeader, *NSLServicesListHeaderPtr;


// some defs for common protocols
#define    kSLPProtocolType            "SLP"
#define    kDNSProtocolType            "DNS"
#define    kLDAPProtocolType            "LDAP"
#define kNBPProtocolType            "NBP"

// general information from a plug-in.  Includes supported protocols, data types and services,
// as well as an info/comment string describing the function of the plug-in in human-readable
// form.  The offsets point to the beginning of each list of data returned, and the protocol
// data offset is the startOfData member of the struct
typedef struct PluginData {
    long        reserved1;
    long        reserved2;
    long        reserved3;
    Boolean        isPurgeable;
    UInt16        totalLen;                        // length of everything, including header
    UInt16        dataTypeOffset;
    UInt16        serviceListOffset;
    UInt16        protocolListOffset;
    UInt16        commentStringOffset;
//    char*        startOfData;                    // protocol data is first on the list
} PluginData, *PluginDataPtr;


#define kNSLDataTypeNSL        'NSL_'

//-----------------------------------------------------------------------------
//    Basic API Utility calls: sufficient to create, and parse data structures
//-----------------------------------------------------------------------------

pascal NSLServicesList    NSLMakeNewServicesList( char* initialServiceList );
pascal NSLError            NSLAddServiceToServicesList( NSLServicesList serviceList, NSLServiceType serviceType );
pascal void                NSLDisposeServicesList( NSLServicesList theList );

pascal NSLNeighborhood    NSLMakeNewNeighborhood( char* name, char* protocolList );    // the name reflects the name of the Neighborhood
                                                                                    // i.e. "apple.com." or "DA3 4th - North"
                                                                                    // the protocolList is a comma delimited list of
                                                                                    // protocols that the Neighborhood might exist in.
                                                                                    // If the user passes in NULL, then all protocols will
                                                                                    // be queried.  Result must be disposed of by user by
                                                                                    // calling NSLFreeNeighborhood.
pascal NSLNeighborhood    NSLFreeNeighborhood( NSLNeighborhood neighborhood );

pascal void NSLGetNameFromNeighborhood( NSLNeighborhood neighborhood, char** name, long* length );

// create a block of formatted data, pointed to by newDataPtr.  This will be used
// in calls (typically request-related calls) for plug-ins that handle the NSL data type.
pascal OSStatus NSLMakeRequestPB(    NSLServicesList serviceList,
                                    NSLAttribute attribute,
                                    TypedDataPtr* newDataPtr );

// provides the inverse of NSLMakeRequestPB, filling out the offsets found within newDataPtr
pascal OSStatus NSLParseRequestPB(    TypedDataPtr newDataPtr,
                                    UInt16* serviceListOffset,
                                    UInt16* attributeOffset );

// same idea as above, used to register a service with a NSL-aware plug-in(s)
pascal OSStatus NSLMakeRegistrationPB(    NSLAttribute attribute,
                                        NSLPath urlToService,
                                        TypedDataPtr* newDataPtr );

// used by plugins to parse a registrationPB
pascal OSStatus NSLParseRegistrationPB(    TypedDataPtr newDataPtr,
                                        char**    attributePtr,
                                        UInt16*    attributeLen,
                                        char**    urlPtr,
                                        UInt16* urlLen );

// releases any storage created with MakeXXXPB calls, associated with TypedData.
pascal TypedDataPtr NSLFreeTypedDataPtr( TypedDataPtr nslTypeData );

// utility function that returns whether a url was found, a pointer to the beginning
// of the url, and the length of the URL.
pascal Boolean NSLGetNextUrl( ClientAsyncInfoPtr infoPtr, char** urlPtr, long* urlLength );

// utility function that returns whether a Neighborhood was found, a pointer to the beginning
// of the Neighborhood, and the length of the Neighborhood.
pascal Boolean NSLGetNextNeighborhood( ClientAsyncInfoPtr infoPtr, NSLNeighborhood* neighborhood, long* neighborhoodLength );


//
// NSLErrNumToString:    convert a numeric error code to its string equivalent.  Caller must
//                         have allocated sufficient space to store both strings.  (Max 255 chars each)
//
//                        The errorString parameter will return a textual explanation of what is wrong,
//                        while the solutionString returns a possible solution to get around the problem
//

pascal OSStatus    NSLErrorToString(NSLError theErr, char* errorString, char* solutionString);


//-----------------------------------------------------------------------------
//    Basic API calls: sufficient to create simple requests, and receive answers
//-----------------------------------------------------------------------------

pascal OSStatus    NSLOpenNavigationAPI( NSLClientRef* newRef );
pascal void        NSLCloseNavigationAPI( NSLClientRef theClient );

//
//    NSLPrepareRequest:    creates an NSLRequestRef, sets up some internal data
//
//    notifier is an NSLNotifyProcPtr that will be called when data is available, when the lookup has completed, or if an error occurs.
//    when the notifier is called, the cookie will be the NSLRequestRef.  If notifier is NULL, then
// the NSLManager will assume that the request is made synchronously.  This should only be used
// while in a separate thread, so that the client app can still process events, etc.
//
//    contextPtr is a void* which is passed as the contextPtr argument when the notifier is called.
//
//    upon exit:
//    1) ref will contain a pointer to a NSLRequestRef which must be passed to all other functions
//    which require a NSLRequestRef.
//
//    2) infoPtr will point to a newly created ClientAsycnInfoPtr which will be disposed by the manager when the search is completed
//
//    NOTE: Only one search can be running at a time per clientRef.

pascal NSLError NSLPrepareRequest(    NSLClientNotifyProcPtr    notifier,
                                    void*                    contextPtr,
                                    NSLClientRef            theClient,
                                    NSLRequestRef*            ref,
                                    char*                    bufPtr,
                                    unsigned long            bufLen,
                                    ClientAsyncInfoPtr*        infoPtr);


//
// NSLStartNeighborhoodLookup: looking for neighborhoods associated with or neighboring a particular neighborhood
//
//    Passing in NULL for neighborhood will generate a list of a default neighborhood(s)
//

pascal NSLError NSLStartNeighborhoodLookup( NSLRequestRef ref,
                                            NSLNeighborhood neighborhood,
                                            ClientAsyncInfo* asyncInfo );

//
// NSLStartServicesLookup: starts looking for entities if the specified type in the specified neighborhood
//

pascal NSLError    NSLStartServicesLookup(    NSLRequestRef ref,
                                        NSLNeighborhood neighborhood,
                                        TypedDataPtr requestData,
                                        ClientAsyncInfo* asyncInfo );


//
// NSLContinueLookup:  continues a paused/outstanding lookup
//

pascal NSLError    NSLContinueLookup( ClientAsyncInfo* asyncInfo );


//
// NSLCancelRequest: cancels an ongoing search
//

pascal NSLError    NSLCancelRequest( NSLRequestRef ref );

//
// NSLDeleteRequest: deletes info associated with this ref.  The ClientAsyncInfoPtr will no longer be valid
//    This must be called when the client is no longer using this requestRef.
//

pascal NSLError    NSLDeleteRequest( NSLRequestRef ref );

//
// NSLRegisterService: registers a service type
//

pascal NSLError NSLRegisterService( TypedDataPtr requestData );

//
// NSLDeRegisterService: unregisters a service
//

pascal NSLError NSLDeregisterService( TypedDataPtr requestData );



#if __cplusplus
}
#endif

#pragma export off


#endif